HPAVC

home *** CD-ROM | disk | FTP | other *** search

/ HPAVC / HPAVC CD-ROM.iso / pc / FAQSYS18.ZIP / FAQS.DAT / BWSTRUCT.DOC < prev next >

Wrap

Text File | 1996-01-04 | 50.6 KB | 1,044 lines

The Blue Wave Offline Mail System Mail Packet File Structures Revision Level 2 Copyright 1990-1994 by Cutting Edge Computing All Rights Reserved Created by George Hatchew Documentation by Martin Pollard and George Hatchew Revision 2.01 - January 18, 1994 =================== TABLE OF CONTENTS =================== Introduction ...................................................... 3 Filename Conventions .............................................. 3 Files in Blue Wave Packets ........................................ 4 Byte Ordering in File Structures .................................. 6 Using the File Structures ......................................... 6 Unused and Reserved Structure Fields .............................. 7 The *.INF File (INF_HEADER & INF_AREA_INFO) ....................... 8 The *.MIX File (MIX_REC) .......................................... 10 The *.FTI File (FTI_REC) .......................................... 11 The *.DAT File .................................................... 12 The *.XTI File (XTI_REC) .......................................... 12 The *.UPL File (UPL_HEADER & UPL_REC) ............................. 12 The *.UPI (UPI_REC) and *.NET (NET_REC) Files ..................... 14 The *.REQ File (REQ_REC) .......................................... 14 The *.PDQ File (PDQ_HEADER & PDQ_REC) ............................. 14 Appendix A - How to Create a Blue Wave Mail Packet ................ 15 Appendix B - How to Create a Blue Wave Reply Packet ............... 16 Appendix C - The Blue Wave Structures and Turbo Pascal ............ 16 Appendix D - Serial Numbers in Mail and Reply Packets ............. 18 ============================ COPYRIGHT AND RESTRICTIONS ============================ The Blue Wave packet structures were created by George Hatchew, and are the copyrighted property of Cutting Edge Computing. Permission is granted for third parties to use these structures in their own pro- grams, without any royalties or licenses required. Cutting Edge Computing reserves the right to make any changes to these structures, at any time. As such, third parties are requested not to make any unauthorized changes to these structures, as Cutting Edge Computing is not bound to follow these changes. Any proposed changes should be brought to the attention of Cutting Edge Computing, where they may be included in future revisions of the structures. Authors that use these structures are allowed to claim that their programs are "Blue Wave compatible". However, to avoid confusion and complications, authors are NOT allowed to use "Blue Wave" as any part of the name of their programs (as "Blue Wave" is a product line from, as well as a trademark of, Cutting Edge Computing). =================== TRADEMARK NOTICES =================== The following are products, trademarks, or registered trademarks of the following individuals and/or companies: ARC - System Enhancement Associates Blue Wave - George Hatchew and Cutting Edge Computing FidoNet - Tom Jennings and Fido Software MegaReader - Kip Compton MS-DOS - Microsoft Corp. PKZIP - PKWARE Inc. QWK - Mark "Sparky" Herring Silver Xpress - Hector Santos and Santronics Software Turbo Pascal, Borland Pascal - Borland International XRS - Michael Y. Ratledge Any omissions from this list are purely unintentional. Blue Wave Mail Packet File Structures - Revision Level 2 INTRODUCTION ============ The world of offline mail has virtually exploded since the late 1980s, due mostly to the ever-increasing interest in electronic mail networks (such as FidoNet and the Internet). As the flow of mail increased, more and more users became aware of the benefits of downloading mail, reading it offline, and uploading replies at a later date, thus maxi- mizing efficiency and minimizing the time spent online. Several competing formats for storage of offline mail have come into existence during this period, with the minimalist QWK format emerging as the dominant one due to its open specifications. (The MegaReader, Silver Xpress, and XRS, formats also exist, but never really achieved "critical mass" due to the proprietary nature of their file formats.) QWK enjoys widespread popularity, but its technical limitations make it less than suitable for handling the wide variety of electronic mail that currently exists (and which will appear in the coming years). The Blue Wave format was designed as a superior method of providing offline mail capabilities, particularly for networks based on the FidoNet standard (which means full support for FidoNet-style private mail, or NetMail). Its design is simple enough that virtually any programmer can create a Blue Wave-compatible product in a short amount of time, yet flexible enough to provide plenty of room for future needs (such as FAX capabilities). It also has basic support for non- FidoNet style mail, such as that required by Internet mail, Usenet newsgroups, and QWK-based network mail. NOTE THAT THIS IS A REFERENCE DOCUMENT, NOT A PROGRAMMING TUTORIAL. A tutorial on programming is beyond the scope of this document. Thus, we do not recommend the use of these structures by the novice. FILENAME CONVENTIONS ==================== The Blue Wave format was originally designed for the Blue Wave series of offline mail readers and doors running on an Intel-compatible PC using MS-DOS (or a DOS-compatible operating system). This means that filenames are limited to the DOS standard "8.3" format (up to eight characters, optionally followed by a period and a one to three charac- ter extension, with no distinction made between upper and lower case letters). For maximum compatibility across different platforms, programs utilizing the Blue Wave format should limit filenames to the DOS format as well. Additionally, DOS allows for some non-alphanumeric characters to be used in filenames. These characters, while suitable for DOS, may cause problems on non-DOS platforms. Therefore, it would be wise to restrict the allowable characters in filenames to uppercase letters ("A" to "Z") and digits ("0" to "9"). - Page 3 - Blue Wave Mail Packet File Structures - Revision Level 2 FILES IN BLUE WAVE PACKETS ========================== There are two main components to the Blue Wave system: mail packets, which consist of messages obtained from the host system (such as a BBS), and reply packets, which consist of messages written by the user via an offline mail reader (such as the reader that bears its name, the Blue Wave Offline Mail Reader). Each type of packet contains its own set of unique files. Blue Wave mail and reply packet filenames are based around what is called a "packet ID". The packet ID is a one to eight character string that uniquely identifies a particular host system, and is used as the basis for all packet files. "Packets", as defined here, are groups of files contained in an archive file, which uses the packet ID as the base filename and is created using a file archive utility (such as ARC or PKZIP, or the equivalent for non-DOS platforms). The three- character extension for a mail packet is comprised of the first two letters of the day of the week, followed by a digit from 0 to 9. FidoNet SysOps will recognize this as the same scheme used for the extensions on EchoMail packets. (An alternate scheme is to use a pure numerical extension, i.e. "001" through "999".) The extension for a reply packet is "NEW". (Note that door implementations should include code to keep track of the last mail packet extension used, so that multiple mail packets created on the same day won't have the same filename.) Examples of packet archive names and internal filenames, based around the packet ID, are given below (after the list of files). A mail packet consists of, at minimum, the following files: *.INF Information about the host system and its message areas, as well as information about the user who obtained the mail packet. *.FTI The headers for each message in the mail packet. The headers consist of such things as the From:, To:, and Subject: fields, and the date/time the message was written. *.MIX An index file that points to the messages for each message area, designed for quick access to messag- es. *.DAT The text for all messages in the mail packet. Optional text/ANSI files may also be included in the archive. In addition to the "reader" files specified in the *.INF header, there are two other types of files, not defined in the *.INF header, that may be included. The first, a list of new files available for down- load, can be included as "NEWFILES.*" (any extension is valid). The second, system bulletins, can be included as "BLT*.*" (any filename is valid, as long as it begins with "BLT"). The methods used to display these bulletins is implementation dependent. - Page 4 - Blue Wave Mail Packet File Structures - Revision Level 2 A reply packet consists of, at minimum, the following files: *.UPL Contains the information (name, network address, message attributes, filename of message text, etc.) for each reply message. Replaces the *.UPI and *.NET files (see below) used in older Blue Wave implementations. *.UPI Contains the information (name, network address, message attributes, filename of message text, etc.) for each non-NetMail reply message. This file has been obsoleted by the *.UPL file, but is documented here for compatibility purposes (as some older systems are not yet compatible with the *.UPL file). *.NET Contains the information (name, network address, message attributes, filename of message text, etc.) for each NetMail reply message. This file has been obsoleted by the *.UPL file, but is documented here for compatibility purposes (as some older systems are not yet compatible with the *.UPL file). *.REQ An optional file that specifies the information on file requests made through the offline mail read- er. *.PDQ An optional file that specifies the information on remote configuration (such as adding and dropping message areas) made through the offline mail reader. To clarify, let's say a BBS is using the packet ID of "WILDBLUE". A mail packet from that BBS would contain (at minimum) the files WILD- BLUE.INF, WILDBLUE.FTI, WILDBLUE.MIX, and WILDBLUE.DAT, and when archived, would be called "WILDBLUE.SU1" (the extension may differ, depending on the criteria described above). Consequently, a reply packet destined for that BBS would contain (at minimum) the files WILDBLUE.UPL, WILDBLUE.NET and WILDBLUE.UPI (for compatibility), plus the individual files that comprise reply messages, and when archived, would be called "WILDBLUE.NEW". The text of each reply message is stored in individual files in the reply packet. Each *.UPL record contains the name of the text file corresponding to the particular reply message. The naming convention used to assign names to each text file is up to the programmer. (The Blue Wave reader uses "xxx.yyy", which stands for "message 'xxx' in area 'yyy', but you are not limited to this format as long as the filename is properly stored in the *.UPL, *.UPI, or *.NET record.) - Page 5 - Blue Wave Mail Packet File Structures - Revision Level 2 BYTE ORDERING IN FILE STRUCTURES ================================ Since the Blue Wave packet structures were initially written for IBM PCs and compatible systems, the format for multi-byte fields in the data structures is expected to be in Intel format (i.e. the least significant byte first, followed by the most significant byte[s]). Some CPUs, particularly the Motorola 68000 series, store multi-byte fields as most significant byte first. If you are writing a Blue Wave compatible program for a system that does not store data in the Intel format, you will have to write a routine that will convert data bet- ween the two formats. USING THE FILE STRUCTURES ========================= The file structures, as presented here, are provided as a header file for use with the C programming language. Simply use the #include statement in your program source code to incorporate the header file: #include "bluewave.h" Each file structure is defined as a data structure ("struct") using the "typedef" feature, making it easy to define variables. For exam- ple, to define a variable used to store the *.INF file header, simply use: INF_HEADER infhdr; in your program. To make the structures as compatible across platforms as possible, all data types used in the structures are user-defined via "typedef". For example, to use a 16-bit unsigned integer, the data type "tWORD" is used instead of "unsigned int". This way, data fields are guaranteed to be the same size across platforms. (For more information, refer to the information contained in the BLUEWAVE.H file.) Also, if your program is being written for a CPU that does not store data in Intel format (as described earlier), you should insert: #define BIG_ENDIAN before you include the BLUEWAVE.H file. This will define the data types as arrays of bytes, making it easier to create routines that will convert data fields between Intel format and the format native to your CPU. (Refer to "Byte Ordering in File Structures" for more information.) Several of the file structures -- the *.INF and *.UPL headers -- include fields that define the lengths of the other file structures used in mail and reply packet files. These fields are used to ensure - Page 6 - Blue Wave Mail Packet File Structures - Revision Level 2 that programs can use future releases of the file structures without breaking... as long as programs are coded to use them, that is. Door authors should take the few extra lines of code to fill in the structure length fields. Reader authors need to take the time to code for possible extensions to this file format. If the data fields are LONGER than expected, simply do a seek to move to the next record, and ignore the extra information. (If the data fields are SHORTER than expected, a simple "please upgrade your reader" should suffice. However, you should never encounter a record size smaller than the ones defined here.) Any extra information that is sent in the packets probably would not be crucial, and you may be able to continue with reading the packet anyway. (It should be noted that all Blue Wave doors earlier than the version 3.0 series set these fields to 0, as this extensibility was not added until recently. If the structure sizes are 0, readers should assume that all records are of the sizes defined in the header file as the "ORIGINAL_XXXX_LEN" macros, and should use these macros when field lengths of 0 are encountered. There is no definition for the original length of the *.UPL structures, as the older doors did not recognize the *.UPL file.) To see an example of how to use these structure length fields, refer to the comments in the BLUEWAVE.H file. There, you will see a C code snippet that not only demonstrates the length fields, but the ORIGINAL_XXXX_LEN macros as well. IMPORTANT NOTE: All Blue Wave file structures must be stored in "packed" format (i.e. the compiler must not insert padding between fields in order to force fields onto word boundaries). Most compilers default to "packed" mode, but if yours does not, you must use the appropriate settings or preprocessor directives to set "packed" mode. Failure to do so will all but guarantee that your program will gener- ate incompatible Blue Wave packets! UNUSED AND RESERVED STRUCTURE FIELDS ==================================== Some fields and flags in the Blue Wave structures are either not defined, or are marked as being reserved for future use. THESE AREAS ARE NOT TO BE USED BY PROGRAMMERS, unless otherwise indicated. They are reserved for future expansion and enhancement of the Blue Wave packet structures, and if you use them for your own purposes, you run the risk of making your program incompatible with future updates of the file structures. Furthermore, future structure updates will assume that these unused areas are "garbage-free" (i.e. they are filled with 0 values). In order to cover all bases, then, all unused areas should be set to 0. This can be easily done with the standard C function memset(). For example, using: - Page 7 - Blue Wave Mail Packet File Structures - Revision Level 2 memset(&infhdr, 0, sizeof(INF_HEADER)); before you begin adding information to the *.INF header structure will ensure that all unused fields are set to 0. This should be done before adding information to *ANY* Blue Wave file structure. THE *.INF FILE (INF_HEADER & INF_AREA_INFO) =========================================== The *.INF file consists of two "parts": a header, which contains information about the host system and the user to whom the packet is intended, and a series of records that contain the information on all message bases available on the host system. (The latter is used in a reader both for posting replies and offline configuration.) The header structure is known as INF_HEADER, and the record structure is known as INF_AREA_INFO. Most of the fields in INF_HEADER are self-explanatory. The following fields, however, deserve extra attention: ver Packet version level. This is a crucial field, as it allows doors and readers to determine the revision level of the file structures used to create the packet. Pro- grams should check this field to insure that they can properly handle the packet; doors should store in this field the current packet revision level, shown at the top of this document. readerfiles Files that can be displayed by the reader. These are usually bulletins, sign-on banners, etc. Up to five files can be specified. keywords Specifies the keywords used while bundling messages. Door authors that wish to provide keyword support should refer to the Blue Wave user documentation for more information. filters Same as above, but specifies the filters used while bundling messages. macros Same as above, but specifies the macros used in the door to specify message bundling operations. can_forward Indicates that the user can forward messages to other message areas from within a reader. inf_header_len Length of INF_HEADER used in mail packet. Door authors are required to fill this field; reader authors should use this field to - Page 8 - Blue Wave Mail Packet File Structures - Revision Level 2 properly parse the *.INF file. The current crop of Blue Wave doors properly fill this field, but older versions may not. Refer to the header file for more information on using this field. inf_areainfo_len Same as above, but specifies the length of the INF_AREA_INFO structure. mix_structlen Same as above, but specifies the length of the *.MIX file structure (MIX_REC). fti_structlen Same as above, but specifies the length of the *.FTI file structure (FTI_REC). uses_upl_file A non-zero value in this field indicates that the door which create the mail packet can process reply packets stored in the *.UPL format. If zero, the door can only handle reply packets stored in the older *.UPI and *.NET formats. (These formats are discussed later.) packet_id The packet ID used by the host system, which can be used by readers to properly access mail packet control files even if the mail packet itself has been renamed. (If this field is not filled, readers should assume that the root name of the mail packet is the packet ID.) The INF_AREA_INFO structure fields are defined as follows: areanum The area number on the host system for which the record defines, specified as an ASCII string. This field will correspond to the similar field in the *.MIX structure (dis- cussed later). This does not necessarily have to be a number, so A CASE-INSENSITIVE MATCH SHOULD BE PERFORMED WHEN DOING ANY COMPARISONS USING THIS FIELD. echotag The area tag name for which the record de- fines. This field is used in the reply packet to link reply messages to the destina- tion areas on the host system, and must be unique (i.e. there cannot be two or more identical area tags). title The message area description. area_flags Specifies the unique characteristics of the message area for which the record defines. - Page 9 - Blue Wave Mail Packet File Structures - Revision Level 2 Most of the flags are self-explanatory, as specified in the header file; the network area flags, however, need to be clarified. If the message area is part of a network (i.e. FidoNet), the INF_ECHO flag should be set; this will allow a reader to properly handle network mail. If the area is for private network mail, the INF_NETMAIL flag should also be set. network_type Specifies the network type for which the defined message area belongs. Note that the network type is specified as a full byte value, NOT as a bit flag. (If the INF_ECHO flag is not set, the network type can be ignored, obviously.) THE *.MIX FILE (MIX_REC) ======================== Each record in the *.MIX file points to the beginning of the area in the *.FTI file that contains the header information for messages that were obtained from each message area. Note that *ONLY* the areas for which messages were extracted will have a corresponding *.MIX record. Each structure field is defined as follows: areanum Corresponds to the identical field in the *.INF record for the particular message area. It is used by the reader to coordinate the information between the *.INF and *.MIX records. Again, CASE-INSENSITIVE COMPARISONS SHOULD BE PERFORMED WHEN USING THIS FIELD, as this field does not have to contain a numeri- cal value. totmsgs Total number of messages in this area. Up to 65,535 messages per area are allowed (the limit of an unsigned 16-bit integer). numpers Total number of messages in this area that are directed specifically to the user who bundled the mail packet. This value is usually obtained during message bundling by comparing the name in the "To:" field to the user name for every message, and incrementing a counter if they match. (Reader authors can feel free to disregard this value and perform their own search for personal messages, once the packet is loaded into the program.) - Page 10 - Blue Wave Mail Packet File Structures - Revision Level 2 msghptr Pointer to the first record in the *.FTI file that corresponds to this message area. Note that this specifies the byte offset into the *.FTI file, *NOT* the record number; thus, programmers can use the seek() or lseek() functions to quickly point to the proper section of the *.FTI file. THE *.FTI FILE (FTI_REC) ======================== The *.FTI record specifies the header information for messages in the mail packet, along with additional information such as the length of the message and the pointer to the message stored in the *.DAT file. These records are stored sequentially in the *.FTI file, with all the headers for the first message area stored first, followed by the headers for the second message area, and so forth. Most of the fields are self-explanatory, with the following fields described in more detail: msgnum The message number AS STORED ON THE HOST SYSTEM. This provides an "absolute" message number for use with message threading. replyto Indicates the absolute message number for which this message is a reply (the "previous" message). If zero, there is no previous message. replyat Indicates the absolute message number of a reply to this message (the "next" message). If zero, there is no next message. msgptr Pointer to the start of the message text in the *.DAT file. This is a byte offset, thus a programmer can use the seek() or lseek() functions to quickly point to the proper position in the *.DAT file. msglength Length of the message text (in bytes) plus 1. The addition of 1 is done to compensate for the required space character in front of the message text (described below). flags Bit-mapped message status flags. Note that for FidoNet network messages, these flags are *NOT* stored in the exact same order as specified in the FidoNet technical standards, even though they are identical in function. - Page 11 - Blue Wave Mail Packet File Structures - Revision Level 2 THE *.DAT FILE ============== The *.DAT file contains the text of all messages obtained from the host system. Valid messages begin with an ASCII space character (" ", decimal 32, hexadecimal 20), followed by the message text itself. Note that the space character is *NOT* to be considered a part of the message text; it is simply a marker used to indicate the start of a valid block of text, and *MUST* be present for each message specified in the *.FTI file (even if there is no message text at all). The messages in the *.DAT file should be in the same order as specified in the *.FTI file, though this is not a requirement (due to the fact that the *.DAT file is unstructured). THE *.XTI FILE (XTI_REC) ======================== Each record in the *.XTI file corresponds to a record in the *.FTI file, and specifies extended status information for each message (the "save", "reply", "print", and "delete" flags used by the Blue Wave reader). Note that this file is *NOT* created by any Blue Wave door; it is created on-the-fly by the Blue Wave reader. (The fields and flags used in XTI_REC are self-explanatory, thus they will not be explained here.) NOTE: The *.XTI file is not an official part of the Blue Wave specification. It is documented here solely for the benefit of third-party authors who might wish to create a similar file for their own applications. If so, authors should NOT use the "XTI" extension on their own files if they differ from the XTI_REC format, as this extension is used on the file created by the Blue Wave offline mail reader (which expects the file to use the XTI_REC format). On the other hand, authors CAN use the "XTI" extension AS LONG AS THE XTI_REC FORMAT IS USED. THE *.UPL FILE (UPL_HEADER & UPL_REC) ===================================== The *.UPL file consists of two "parts": a header, which contains information about the reader used to create the reply packet, and a series of records that contain the information on all messages con- tained in the reply packet. Most of the fields in the *.UPL file are self-explanatory. The fol- lowing, however, deserve extra attention, starting with UPL_HEADER: upl_header_len Length of UPL_HEADER used in the reply packet. Reader authors are required to fill this field; door authors should use this field to properly parse the *.UPL file. - Page 12 - Blue Wave Mail Packet File Structures - Revision Level 2 Refer to the header file (under the INF_HEADER section) for more information on using this field. upl_rec_len Same as above, but specifies the length of the UPL_REC structure. reader_tear Contains the abbreviated name of the reader that created the reply packet (i.e. "Blue Wave", "Q-Blue", "Wave Rider", etc.). This text can be used by the door to append tear lines and other reader-identifying lines to the message text, if desired. (Door authors should take steps to use alternate text in case this field is not filled; using the name of the door is usually a good alternative.) Likewise, here is additional detail on several fields in the UPL_REC structure: unix_date The date/time that the reply message was written, specified as the number of seconds since 01/01/1970 (i.e. "Unix-style"). This value can easily be obtained by C programmers via the time() function; in addition, the ANSI C standard library contains additional functions to manipulate a Unix-style time field, enough to satisfy most any require- ment (provided your compiler has support for them, though any compiler that claims to be ANSI C compliant will contain all those functions and more). filename The name of the file that contains the text of the message. There is no requirement on how this file is to be named; such schemes are left to the individual. (The Blue Wave reader uses "xxx.yyy", where "xxx" is the area number -- derived from the "areanum" field in INF_AREA_INFO -- and "yyy" is a unique number for each message that corre- sponds to that area. Note that this is only provided as an example; you are not required to use this scheme, so long as the filenames are properly specified.) area_flags This field is used internally by the Blue Wave reader; as such, it *MUST NOT* be used by any other application. net_dest Used to specify the destination address, as a text string, on messages destined for non- FidoNet networks. (FidoNet addresses are - Page 13 - Blue Wave Mail Packet File Structures - Revision Level 2 specified by the "destzone", "destnet", "destnode", and "destpoint" fields in UPL_REC.) The format of the address is, naturally, dependent on the network in ques- tion. If the message is for a non-networked message area, this field is ignored. THE *.UPI (UPI_REC) AND *.NET (NET_REC) FILES ============================================= The *.UPI and *.NET files are similar to the *.UPL file, in that they specify the information for all messages in the reply packet (*.UPI for non-NetMail messages, *.NET for NetMail messages only). The fields in these files are similar in form and function to those in the *.UPL file, thus they will not be elaborated upon here. *.UPI and *.NET were used in older versions of the Blue Wave reader, and have effectively been replaced by the more informative (and flexible) *.UPL file. However, some older Blue Wave doors cannot handle the new *.UPL file; for this reason, authors should provide support for *.UPI and *.NET, as well as *.UPL. Readers should create all three files, and doors should include code to process all three (giving preferential treatment to *.UPL, of course). Eventually, *.UPI and *.NET will be phased out altogether. THE *.REQ FILE (REQ_REC) ======================== The *.REQ file is simply a list of files that the user wishes to obtain (download) from the host system. The implementation of such a feature is left to the individual programmer. NOTE: Current Blue Wave doors do not allow wildcard characters ("*" and "?") in filenames, nor do they provide support for requesting more than 10 files. These are limitations of the Blue Wave doors themselves, *NOT* of the Blue Wave file specifications. This information is provided merely for informational purposes; authors should not feel bound by these restrictions in their own programs. THE *.PDQ FILE (PDQ_HEADER & PDQ_REC) ===================================== The *.PDQ file is used to perform offline configuration of the door via the reader. This file consists of two parts: a header, which contains non-message area configuration information, and a series of records that indicate the message areas to enable for scanning. The fields in both PDQ_HEADER and PDQ_REC are mostly self-explanatory, though the process of selecting message areas needs elaboration. If - Page 14 - Blue Wave Mail Packet File Structures - Revision Level 2 the PDQ_AREA_CHANGES flag is set (in the "flags" field of PDQ_HEADER), the door should enable all the message areas (specified in PDQ_REC records) that follow the header. This is most easily accomplished by first turning OFF all message areas that were active, then turning ON each area indicated by the PDQ_REC records (provided the user has access to them on the host system, of course). This is the method used by the Blue Wave doors, as it seems to be the easiest way to accomplish the task. NOTE: This method of performing offline configuration WILL change in a subsequent revision of the Blue Wave specifications, so be ready for it! APPENDIX A - HOW TO CREATE A BLUE WAVE MAIL PACKET ================================================== The following steps outline the basic method for creating a Blue Wave mail packet. Note that this outline is HIGHLY generalized; the details of such a process are left to the programmer to implement as desired. 1. Open the *.INF, *.MIX, *.FTI, and *.DAT files for writing; if they currently exist, they should be truncated and overwritten. 2. Fill the INF_HEADER structure and write it to the *.INF file. 3. Obtain the information for the first message area, fill the INF_AREA_INFO structure, and writing it to the *.INF file. 4. Repeat step 3 for all remaining message areas. 5. Scan through the messages for the first message area and determine how many messages need to be packed. If messages need to be packed, fill the MIX_REC structure and write it to the *.MIX file, then perform the following steps: a. Read the next new message from the message area. b. Fill the FTI_REC structure and write it to the *.FTI file. c. Write the message text to the *.DAT file. d. Repeat steps a through c until all messages are packed. 6. Repeat step 5 for all remaining message areas. NOTE: An alternate method for the actions described in steps 5 and 6 is to scan through the message base and write the FTI_REC records and the *.DAT text first, then write the MIX_REC. As mentioned above, however, the method you use is entirely up to you. - Page 15 - Blue Wave Mail Packet File Structures - Revision Level 2 7. Use an archiving utility (ARC, PKZIP, etc.) to pack the *.INF, *.MIX, *.FTI, and *.DAT files into an archive file. The file should be named according to the naming convention specified earlier in this document. Note that these steps do not take into account such things as bulletin files, keywords, filters, macros, and so forth, but again, these are the details which are left to the programmer to implement. APPENDIX B - HOW TO CREATE A BLUE WAVE REPLY PACKET =================================================== Unlike creating a mail packet, the creation of a reply packet is not a linear process; there is no outline that can be followed. Basically, when the reader creates a reply message, a UPL_REC record is filled and written to the *.UPL file for each reply created by the reader; if the *.UPL file doesn't exist, then it will have to be created (natu- rally) by filling and writing a UPL_HEADER to the *.UPL file before adding UPL_REC records. This process is performed on-the-fly, at the time the user creates reply messages. The reply archive itself is created by an archive utility (ARC, PKZIP, etc.), using the filename conventions specified earlier in this docu- ment. In order to prevent "orphaned" files -- messages deleted by the reader -- from showing up in the reply archive, reader authors should delete the archive before running the archive utility; this will force a "fresh" file, free from excess clutter, to be created from scratch. APPENDIX C - THE BLUE WAVE STRUCTURES AND TURBO PASCAL ====================================================== The Blue Wave packet structures are provided as a header file for C compilers, since the Blue Wave Offline Mail Reader and the Blue Wave Offline Mail Doors from Cutting Edge Computing are written in C. However, for the convenience of programmers who write programs using Borland's Pascal compilers (Turbo Pascal and Borland Pascal), a header file for use in Pascal programs (BLUEWAVE.INC) is provided. Please note the following changes and restrictions from the C header imple- mentation: 1. As implemented, the Pascal header is to be included within a source file, i.e.: {$I bluewave.inc} Industrious Pascal programmers can easily convert this header file to a unit if so desired. 2. The structure names and constants remain identical, i.e. MIX_REC, FTI_REC, and so on, and are defined as "record" data types. Thus, defining a structure is similar to any other Pascal data - Page 16 - Blue Wave Mail Packet File Structures - Revision Level 2 type, i.e.: var infheader : INF_HEADER; infrec : INF_AREA_INFO; mixrec : MIX_REC; ftirec : FTI_REC; Also note that unlike C, Pascal is not case-sensitive with re- gards to variable and type names. Thus, INF_HEADER can also be accessed as "inf_header", "Inf_Header", or even "InF_HeAdEr". 3. Due to a conflict with reserved keywords in Pascal, the "from" and "to" fields in FTI_REC, MSG_REC, UPI_REC, and UPL_REC have been renamed to "mfrom" and "mto". All other field names are identical between the C and Pascal headers. 4. Bit flags are defined as sets in the Pascal header, and are set and reset using the Pascal set operators (+ and -). For example, to set the INF_ECHO and INF_NETMAIL flags, the following state- ment: infrec.area_flags := infrec.area_flags + [INF_ECHO, INF_NETMAIL]; can be used. 5. With one exception, data types in Pascal are stored identically to their C counterparts (i.e. Pascal "longint" and C "long int" are stored, identically, in 4 bytes.). The lone exception is strings. In C, strings are stored as a series of characters terminated with a 0 byte. In Pascal, strings are stored as a length byte followed by the characters that make up the string. Since the Blue Wave format is centered around the C language, Pascal programmers will have to convert strings between C and Pascal formats. To aid in this endeavor, strings in the Pascal header are defined as arrays of bytes (i.e. "array[1..43] of byte"), but YOU will have to devise your own routines to convert strings between the two formats. There are undoubtedly other areas where C and Pascal differ, but this should get you started in the right direction. PLEASE NOTE THAT CUTTING EDGE COMPUTING DOES NOT PROVIDE SUPPORT FOR PASCAL PROGRAMMERS USING THESE STRUCTURES. The Pascal header is provided solely for your convenience; other than that, you are on your own. Thus, it is recommended that only Pascal programmers with some experience in using data created by (and expected by) C programs use these structures, as handling the differences between the languages is not something that is easily handled by the novice. - Page 17 - Blue Wave Mail Packet File Structures - Revision Level 2 APPENDIX D - SERIAL NUMBERS IN MAIL AND REPLY PACKETS ===================================================== The serial number fields in the *.INF, *.UPI, and *.UPL structures are used mainly by the Blue Wave reader and doors from Cutting Edge Com- puting (using what is, naturally, a proprietary algorithm to determine the actual serial numbers). Authors are free to use these fields as they see fit, though the values in the fields will undoubtedly be meaningless to other Blue Wave-compatible programs. In fact, unless you're creating your own series of Blue Wave-compatible doors and readers, the serial number fields are practically useless to third- party authors. (As an example, the Blue Wave doors will examine the reader name field in the *.UPL header to determine if a reply packet was created by the Blue Wave reader. If it was, then the serial number is used to deter- mine if "[NR]" should be added to the tear line. On the other hand, if the packet was created by a different reader, the Blue Wave doors will ignore the serial number and never put "[NR]" in the tear line.) - Page 18 -